<HTML>
<BODY>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->

<B><A HREF="SOCKET.html">SOCKET(2)</A></B>		  FreeBSD System Calls Manual		     <B><A HREF="SOCKET.html">SOCKET(2)</A></B>


</PRE>
<H2>NAME</H2><PRE>
     <B>socket</B> - create an endpoint for communication


</PRE>
<H2>SYNOPSIS</H2><PRE>
     <B>#include</B> <B>&lt;sys/types.h&gt;</B>
     <B>#include</B> <B>&lt;sys/socket.h&gt;</B>

     <I>int</I>
     <B>socket</B>(<I>int</I> <I>domain</I>, <I>int</I> <I>type</I>, <I>int</I> <I>protocol</I>)


</PRE>
<H2>DESCRIPTION</H2><PRE>
     <B>Socket</B>() creates an endpoint for communication and returns a descriptor.

     The <I>domain</I> parameter specifies a communications domain within which com-
     munication will take place; this selects the protocol family which should
     be used.  These families are defined in the include file &lt;<I>sys/socket.h</I>&gt;.
     The currently understood formats are

	   PF_LOCAL	   (Host-internal protocols, formerly called PF_UNIX),
	   PF_INET	   (ARPA Internet protocols),
	   PF_ISO	   (ISO protocols),
	   PF_CCITT	   (ITU-T protocols, like X.25),
	   PF_NS	   (Xerox Network Systems protocols), and

     The socket has the indicated <I>type</I>, which specifies the semantics of com-
     munication.  Currently defined types are:

	   SOCK_STREAM
	   SOCK_DGRAM
	   SOCK_RAW
	   SOCK_SEQPACKET
	   SOCK_RDM

     A SOCK_STREAM type provides sequenced, reliable, two-way connection based
     byte streams.  An out-of-band data transmission mechanism may be support-
     ed.  A SOCK_DGRAM socket supports datagrams (connectionless, unreliable
     messages of a fixed (typically small) maximum length).  A SOCK_SEQPACKET
     socket may provide a sequenced, reliable, two-way connection-based data
     transmission path for datagrams of fixed maximum length; a consumer may
     be required to read an entire packet with each read system call.  This
     facility is protocol specific, and presently implemented only for PF_NS.
     SOCK_RAW sockets provide access to internal network protocols and inter-
     faces.  The types SOCK_RAW, which is available only to the super-user,
     and SOCK_RDM, which is planned, but not yet implemented, are not de-
     scribed here.

     The <I>protocol</I> specifies a particular protocol to be used with the socket.
     Normally only a single protocol exists to support a particular socket
     type within a given protocol family.  However, it is possible that many
     protocols may exist, in which case a particular protocol must be speci-
     fied in this manner.  The protocol number to use is particular to the
     communication domain in which communication is to take place; see
     <B><A HREF="protocols.html">protocols(5)</A></B>.

     Sockets of type SOCK_STREAM are full-duplex byte streams, similar to
     pipes.  A stream socket must be in a <I>connected</I> state before any data may
     be sent or received on it.  A connection to another socket is created
     with a <B><A HREF="connect.html">connect(2)</A></B> call.  Once connected, data may be transferred using
     <B><A HREF="read.html">read(2)</A></B> and <B><A HREF="write.html">write(2)</A></B> calls or some variant of the <B><A HREF="send.html">send(2)</A></B> and <B><A HREF="recv.html">recv(2)</A></B>
     calls.  (Some protocol families, such as the Internet family, support the
     notion of an ``implied connect,'' which permits data to be sent piggy-
     backed onto a connect operation by using the <B><A HREF="send.html">sendto(2)</A></B> call.)  When a
     session has been completed a <B><A HREF="close.html">close(2)</A></B> may be performed.  Out-of-band data
     may also be transmitted as described in <B><A HREF="send.html">send(2)</A></B> and received as described
     in <B><A HREF="recv.html">recv(2)</A></B>.

     The communications protocols used to implement a SOCK_STREAM insure that
     data is not lost or duplicated.  If a piece of data for which the peer
     protocol has buffer space cannot be successfully transmitted within a
     reasonable length of time, then the connection is considered broken and
     calls will indicate an error with -1 returns and with ETIMEDOUT as the
     specific code in the global variable <I>errno</I>. The protocols optionally keep
     sockets ``warm'' by forcing transmissions roughly every minute in the ab-
     sence of other activity.  An error is then indicated if no response can
     be elicited on an otherwise idle connection for a extended period (e.g. 5
     minutes).	A SIGPIPE signal is raised if a process sends on a broken
     stream; this causes naive processes, which do not handle the signal, to
     exit.

     SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM sock-
     ets.  The only difference is that <B><A HREF="read.html">read(2)</A></B> calls will return only the
     amount of data requested, and any remaining in the arriving packet will
     be discarded.

     SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to correspon-
     dents named in <B><A HREF="send.html">send(2)</A></B> calls.  Datagrams are generally received with
     <B><A HREF="recv.html">recvfrom(2)</A></B>,  which returns the next datagram with its return address.

     An <B><A HREF="fcntl.html">fcntl(2)</A></B> call can be used to specify a process group to receive a
     SIGURG signal when the out-of-band data arrives.  It may also enable non-
     blocking I/O and asynchronous notification of I/O events via SIGIO.

     The operation of sockets is controlled by socket level <I>options</I>. These op-
     tions are defined in the file &lt;<I>sys/socket.h</I>&gt;. <B><A HREF="getsockopt.html">Setsockopt(2)</A></B> and getsock-
     <B><A HREF="getsockopt.html">opt(2)</A></B> are used to set and get options, respectively.


</PRE>
<H2>RETURN VALUES</H2><PRE>
     A -1 is returned if an error occurs, otherwise the return value is a de-
     scriptor referencing the socket.


</PRE>
<H2>ERRORS</H2><PRE>
     The <B>socket</B>() call fails if:

     [EPROTONOSUPPORT]	The protocol type or the specified protocol is not
			supported within this domain.

     [EMFILE]		The per-process descriptor table is full.

     [ENFILE]		The system file table is full.

     [EACCES]		Permission to create a socket of the specified type
			and/or protocol is denied.

     [ENOBUFS]		Insufficient buffer space is available.  The socket
			cannot be created until sufficient resources are
			freed.


</PRE>
<H2>SEE ALSO</H2><PRE>
     <B><A HREF="accept.html">accept(2)</A></B>,  <B><A HREF="bind.html">bind(2)</A></B>,  <B><A HREF="connect.html">connect(2)</A></B>,	<B><A HREF="getpeername.html">getpeername(2)</A></B>,  <B><A HREF="getsockname.html">getsockname(2)</A></B>,
     <B><A HREF="getsockopt.html">getsockopt(2)</A></B>,  <B><A HREF="ioctl.html">ioctl(2)</A></B>,	<B><A HREF="listen.html">listen(2)</A></B>,  <B><A HREF="read.html">read(2)</A></B>,  <B><A HREF="recv.html">recv(2)</A></B>,	<B><A HREF="select.html">select(2)</A></B>,
     <B><A HREF="send.html">send(2)</A></B>,  <B><A HREF="shutdown.html">shutdown(2)</A></B>,  <B><A HREF="socketpair.html">socketpair(2)</A></B>,  <B><A HREF="write.html">write(2)</A></B>,	<B><A HREF="getprotoent.html">getprotoent(3)</A></B>,  pro-
     <B><A HREF="tocols.html">tocols(5)</A></B>

     "An Introductory 4.3 BSD Interprocess Communication Tutorial", <I>PS1</I>, 7.

     "BSD Interprocess Communication Tutorial", <I>PS1</I>, 8.


</PRE>
<H2>HISTORY</H2><PRE>
     The <B>socket</B>() function call appeared in 4.2BSD.
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
